Analyzing complex data
Complex data consists of multiple data values treated as a group. A Web service can exchange complex data with a client using three different SOAP message data elements:
The techniques available for a Progress 4GL client to access this complex data depend on the structure and content of the data as determined by the WSDL Analyzer. If the Analyzer determines that it is possible, it indicates that you can access the complex data using a Progress 4GL temp-table or ProDataSet and how to define it in your code. If the Analyzer cannot identify a temp-table or ProDataSet to represent an instance of complex data, it provides an example SOAP message element, depending on where it appears in the SOAP message, so you can use 4GL features to access the XML data as a Document Object Model (DOM) tree or read and write the data using the Simple API for XML (SAX).
If the Analyzer identifies an appropriate temp-table or ProDataSet to represent the complex data, you can manage the data in your 4GL program much more easily than using the 4GL DOM or SAX features. Access to such data relies entirely on 4GL data types and requires no transformation to and from XML. You always have the option of using the DOM or SAX features to access the XML directly, but you are only required to do this if the Analyzer cannot identify a temp-table or ProDataSet definition to represent the complex data.
The following sections provide more information on how the Analyzer interprets and represents complex data for each of the three SOAP data components with examples of Analyzer output you might see:
Web service operation parameter documentation
When the Analyzer identifies a Web service operation parameter as a static temp-table or ProDataSet, it documents the appropriate TABLE or DATASET parameter in the Progress 4GL procedure or user-defined function signature. It then provides the 4GL definition for the corresponding static temp-table or ProDataSet that you can use in your application. You can then access and manage the TABLE or DATASET parameter as in any 4GL application.
If it identifies the parameter as a dynamic temp-table, as passed by a Progress 4GL Web service, the Analyzer documents a corresponding TABLE-HANDLE parameter in the Progress 4GL procedure or user-defined function signature. You can then access and manage the dynamic temp-table parameter as in any 4GL application.
If it identifies the parameter as a possible dynamic temp-table or ProDataSet, the Analyzer documents the corresponding parameter as a LONGCHAR in the Progress 4GL procedure or user-defined function signature, along with a note suggesting you contact the Web service provider for more information on whether and how you can access the parameter as a dynamic temp-table or ProDataSet. If you can do so, you can use an appropriate TABLE-HANDLE or DATASET-HANDLE parameter in place of the documented LONGCHAR in the Progress 4GL procedure or user-defined function signature.
If the Analyzer cannot identify any case for a temp-table or ProDataSet mapping, it documents the parameter as a LONGCHAR in the Progress 4GL procedure or user-defined function signature and provides an example SOAP message element for the complex data. In all cases where the Analyzer identifies a temp-table or ProDataSet mapping, it also provides a link to documentation containing an example SOAP message element, in case you prefer to work with the XML directly.
For more information on how to use the 4GL to work with complex data passed as a parameter, see Chapter 10, " Invoking Web Service Operations from the Progress 4GL."
SOAP header entry documentation
For a SOAP header entry, the Analyzer provides similar documentation for complex data as for a Web service operation parameter, except that it does not specify 4GL parameter data types. If it can identify a temp-table or ProDataSet that matches the SOAP header entry, it simply provides the appropriate static 4GL definition. If a dynamic temp-table or ProDataSet mapping is possible, the Analyzer also documents this fact with any appropriate explanatory notes.
Note: SOAP headers rarely contain complex data that the Analyzer can map to a temp-table or ProDataSet.Unlike operation parameters, for SOAP header entries, you never access a temp-table or ProDataSet directly in the header. Instead, for a response header, you must access the header entry XML and use a 4GL temp-table or ProDataSet XML read method to transform the XML into temp-table or ProDataSet data, which you can then access as 4GL data types. Likewise, for a request header, you can create the header data in the corresponding temp-table or ProDataSet and transform it to the header entry XML using a temp-table or ProDataSet XML write method. Again, if no temp-table or ProDataSet mapping is possible, you must use the 4GL DOM or SAX features to access the XML for a header entry.
For more information on how to use the 4GL to work with complex data passed as a SOAP header entry, see Chapter 11, " Handling SOAP Message Headers in the Progress 4GL."
SOAP fault detail documentation
For SOAP fault detail, the Analyzer provides similar documentation for complex data as for a Web service operation parameter, except that it does not specify 4GL parameter data types. If it can identify a temp-table or ProDataSet that matches the SOAP fault detail, it simply provides the appropriate static 4GL definition. If a dynamic temp-table or ProDataSet mapping is possible, the Analyzer also documents this fact with any appropriate explanatory notes.
Note: SOAP fault detail rarely contains complex data that the Analyzer can map to a temp-table or ProDataSet.Unlike operation parameters, for SOAP fault detail, you never access a temp-table or ProDataSet directly. Instead, you must access the SOAP fault detail XML and use a 4GL temp-table or ProDataSet XML read method to transform the XML into temp-table or ProDataSet data, which you can then access as 4GL data types. Again, if no temp-table or ProDataSet mapping is possible, you must use the 4GL DOM or SAX features to access the XML contained in the SOAP fault detail.
For more information on how to use the 4GL to work with complex data passed as SOAP fault detail, see Chapter 12, " Handling Errors in Progress 4GL Requests to Web Services."
Example Analyzer documentation for complex data
Figure 8–13 shows the “Operation (internal procedure) detail” section of a port type document for a procedure that is passing complex data parameters. The WSDL Analyzer has identified static temp-table definitions that can be used for these parameters. So, it specifies TABLE parameters for the procedure signature.
Figure 8–14 shows Progress 4GL examples for temp-table definitions that match the complex data in the Web service operation parameters. Note the XML NODE TYPE "Attribute" phrase in the description of the Name field. This indicates the type of XML node that the Name field is associated with and represents one of the features available in the 4GL to help map temp-tables to XML. For more information on these features, see OpenEdge Development: Programming Interfaces
.
Figure 8–15 shows how this section of the port type document describes the relationship between temp-table or ProDataSet parameters and their underlying XML. In this case, the temp-table is represented by the XML Schema defined by a <ProTempTable> element in the WSDL, which you can see by clicking the ProTempTable link. The parameter description also provides an example of the SOAP element actually sent over the wire between the client and Web service, which you can see by clicking the View example link.
Figure 8–16 shows the example SOAP element that the Analyzer might provide for the customerList parameter. The italic terms (for example, “String-value”) indicate values of various data types that appear in the SOAP element as indicated, including any formatting (such as the quotes in this example).
The Analyzer documents any complex data in SOAP headers and SOAP faults in a similar fashion following the “Parameters” section of this document.